From 205a13eaa0868934e90a6c5643d422668934ef79 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 21 Feb 2021 10:40:24 -0500 Subject: [PATCH] docs: Brush up the Wayland backend docs Add some content here. --- gdk/wayland/gdkdevice-wayland.c | 72 +++++++++++++++++++++--------- gdk/wayland/gdkdisplay-wayland.c | 42 +++++++++++------ gdk/wayland/gdkglcontext-wayland.c | 6 +++ gdk/wayland/gdkmonitor-wayland.c | 16 +++++-- gdk/wayland/gdksurface-wayland.c | 71 +++++++++++++++++++++-------- 5 files changed, 150 insertions(+), 57 deletions(-) diff --git a/gdk/wayland/gdkdevice-wayland.c b/gdk/wayland/gdkdevice-wayland.c index 4692224233..712fcd2a98 100644 --- a/gdk/wayland/gdkdevice-wayland.c +++ b/gdk/wayland/gdkdevice-wayland.c @@ -54,6 +54,28 @@ #include #endif +/** + * GdkWaylandDevice: + * + * The Wayland implementation of `GdkDevice`. + * + * Beyond the regular [class@Gdk.Device] API, the Wayland implementation + * provides access to Wayland objects such as the `wl_seat` with + * [method@GdkWayland.WaylandDevice.get_wl_seat], the `wl_keyboard` with + * [method@GdkWayland.WaylandDevice.get_wl_keyboard] and the `wl_pointer` with + * [method@GdkWayland.WaylandDevice.get_wl_pointer]. + */ + +/** + * GdkWaylandSeat: + * + * The Wayland implementation of `GdkSeat`. + * + * Beyond the regular [class@Gdk.Seat] API, the Wayland implementation + * provides access to the Wayland `wl_seat` object with + * [method@GdkWayland.WaylandSeat.get_wl_seat]. + */ + #define BUTTON_BASE (BTN_LEFT - 1) /* Used to translate to 1-indexed buttons */ #ifndef BTN_STYLUS3 @@ -945,11 +967,11 @@ gdk_wayland_device_pad_init (GdkWaylandDevicePad *pad) /** * gdk_wayland_device_get_wl_seat: (skip) - * @device: (type GdkWaylandDevice): a #GdkDevice + * @device: (type GdkWaylandDevice): a `GdkDevice` * - * Returns the Wayland wl_seat of a #GdkDevice. + * Returns the Wayland `wl_seat` of a `GdkDevice`. * - * Returns: (transfer none): a Wayland wl_seat + * Returns: (transfer none): a Wayland `wl_seat` */ struct wl_seat * gdk_wayland_device_get_wl_seat (GdkDevice *device) @@ -964,11 +986,11 @@ gdk_wayland_device_get_wl_seat (GdkDevice *device) /** * gdk_wayland_device_get_wl_pointer: (skip) - * @device: (type GdkWaylandDevice): a #GdkDevice + * @device: (type GdkWaylandDevice): a `GdkDevice` * - * Returns the Wayland wl_pointer of a #GdkDevice. + * Returns the Wayland `wl_pointer` of a `GdkDevice`. * - * Returns: (transfer none): a Wayland wl_pointer + * Returns: (transfer none): a Wayland `wl_pointer` */ struct wl_pointer * gdk_wayland_device_get_wl_pointer (GdkDevice *device) @@ -983,11 +1005,11 @@ gdk_wayland_device_get_wl_pointer (GdkDevice *device) /** * gdk_wayland_device_get_wl_keyboard: (skip) - * @device: (type GdkWaylandDevice): a #GdkDevice + * @device: (type GdkWaylandDevice): a `GdkDevice` * - * Returns the Wayland wl_keyboard of a #GdkDevice. + * Returns the Wayland `wl_keyboard` of a `GdkDevice`. * - * Returns: (transfer none): a Wayland wl_keyboard + * Returns: (transfer none): a Wayland `wl_keyboard` */ struct wl_keyboard * gdk_wayland_device_get_wl_keyboard (GdkDevice *device) @@ -5033,9 +5055,11 @@ gdk_wayland_seat_set_drag (GdkSeat *seat, /** * gdk_wayland_device_get_data_device: (skip) - * @gdk_device: (type GdkWaylandDevice): a #GdkDevice + * @gdk_device: (type GdkWaylandDevice): a `GdkDevice` + * + * Returns the Wayland `wl_data_device` of a `GdkDevice`. * - * ... + * Returns: (transfer none): a Wayland `wl_data_device` */ struct wl_data_device * gdk_wayland_device_get_data_device (GdkDevice *gdk_device) @@ -5050,10 +5074,13 @@ gdk_wayland_device_get_data_device (GdkDevice *gdk_device) /** * gdk_wayland_device_set_selection: (skip) - * @gdk_device: (type GdkWaylandDevice): a #GdkDevice + * @gdk_device: (type GdkWaylandDevice): a `GdkDevice` * @source: the data source for the selection * - * ... + * Sets the selection of the `GdkDevice. + * + * This is calling wl_data_device_set_selection() on + * the `wl_data_device` of @gdk_device. */ void gdk_wayland_device_set_selection (GdkDevice *gdk_device, @@ -5073,9 +5100,9 @@ gdk_wayland_device_set_selection (GdkDevice *gdk_device, /** * gdk_wayland_seat_get_wl_seat: (skip) - * @seat: (type GdkWaylandSeat): a #GdkSeat + * @seat: (type GdkWaylandSeat): a `GdkSeat` * - * Returns the Wayland `wl_seat` of a #GdkSeat. + * Returns the Wayland `wl_seat` of a `GdkSeat`. * * Returns: (transfer none): a Wayland `wl_seat` */ @@ -5089,18 +5116,19 @@ gdk_wayland_seat_get_wl_seat (GdkSeat *seat) /** * gdk_wayland_device_get_node_path: - * @device: (type GdkWaylandDevice): a #GdkDevice + * @device: (type GdkWaylandDevice): a `GdkDevice` * * Returns the `/dev/input/event*` path of this device. * - * For #GdkDevices that possibly coalesce multiple hardware + * For `GdkDevice`s that possibly coalesce multiple hardware * devices (eg. mouse, keyboard, touch,...), this function * will return %NULL. * * This is most notably implemented for devices of type * %GDK_SOURCE_PEN, %GDK_SOURCE_TABLET_PAD. * - * Returns: (nullable) (transfer none): the `/dev/input/event*` path of this device + * Returns: (nullable) (transfer none): the `/dev/input/event*` + * path of this device */ const char * gdk_wayland_device_get_node_path (GdkDevice *device) @@ -5131,9 +5159,11 @@ gdk_wayland_device_get_node_path (GdkDevice *device) * @feature_idx: 0-indexed index of the feature to set the feedback label for * @label: Feedback label * - * Sets the feedback label for the given feature/index. This may be used by the - * compositor to provide user feedback of the actions available/performed. - **/ + * Sets the feedback label for the given feature/index. + * + * This may be used by the compositor to provide user feedback + * of the actions available/performed. + */ void gdk_wayland_device_pad_set_feedback (GdkDevice *device, GdkDevicePadFeature feature, diff --git a/gdk/wayland/gdkdisplay-wayland.c b/gdk/wayland/gdkdisplay-wayland.c index 673c9d3478..03a38be862 100644 --- a/gdk/wayland/gdkdisplay-wayland.c +++ b/gdk/wayland/gdkdisplay-wayland.c @@ -58,6 +58,20 @@ #include "gdk/gdk-private.h" +/** + * GdkWaylandDisplay: + * + * The Wayland implementation of `GdkDisplay`. + * + * Beyond the regular [class@Gdk.Display] API, the Wayland implementation + * provides access to Wayland objects such as the `wl_display` with + * [method@GdkWayland.WaylandDisplay.get_wl_display], the `wl_compositor` with + * [method@GdkWayland.WaylandDisplay.get_wl_compositor]. + * + * You can find out what Wayland globals are supported by a display + * with [method@GdkWayland.WaylandDisplay.query_registry]. + */ + #define MIN_SYSTEM_BELL_DELAY_MS 20 #define GTK_SHELL1_VERSION 4 @@ -876,7 +890,7 @@ gdk_wayland_display_get_next_serial (GdkDisplay *display) /** * gdk_wayland_display_get_startup_notification_id: - * @display: (type GdkWaylandDisplay): a #GdkDisplay + * @display: (type GdkWaylandDisplay): a `GdkDisplay` * * Gets the startup notification ID for a Wayland display, or %NULL * if no ID has been defined. @@ -891,19 +905,19 @@ gdk_wayland_display_get_startup_notification_id (GdkDisplay *display) /** * gdk_wayland_display_set_startup_notification_id: - * @display: (type GdkWaylandDisplay): a #GdkDisplay + * @display: (type GdkWaylandDisplay): a `GdkDisplay` * @startup_id: the startup notification ID (must be valid utf8) * * Sets the startup notification ID for a display. * - * This is usually taken from the value of the DESKTOP_STARTUP_ID + * This is usually taken from the value of the `DESKTOP_STARTUP_ID` * environment variable, but in some cases (such as the application not * being launched using exec()) it can come from other sources. * * The startup ID is also what is used to signal that the startup is * complete (for example, when opening a window or when calling - * gdk_display_notify_startup_complete()). - **/ + * [method@Gdk.Display.notify_startup_complete]). + */ void gdk_wayland_display_set_startup_notification_id (GdkDisplay *display, const char *startup_id) @@ -1083,7 +1097,7 @@ get_cursor_theme (GdkWaylandDisplay *display_wayland, /** * gdk_wayland_display_set_cursor_theme: - * @display: (type GdkWaylandDisplay): a #GdkDisplay + * @display: (type GdkWaylandDisplay): a `GdkDisplay` * @name: the new cursor theme * @size: the size to use for cursors * @@ -1180,11 +1194,11 @@ _gdk_wayland_display_update_serial (GdkWaylandDisplay *display_wayland, /** * gdk_wayland_display_get_wl_display: (skip) - * @display: (type GdkWaylandDisplay): a #GdkDisplay + * @display: (type GdkWaylandDisplay): a `GdkDisplay` * - * Returns the Wayland wl_display of a #GdkDisplay. + * Returns the Wayland `wl_display` of a `GdkDisplay`. * - * Returns: (transfer none): a Wayland wl_display + * Returns: (transfer none): a Wayland `wl_display` */ struct wl_display * gdk_wayland_display_get_wl_display (GdkDisplay *display) @@ -1196,11 +1210,11 @@ gdk_wayland_display_get_wl_display (GdkDisplay *display) /** * gdk_wayland_display_get_wl_compositor: (skip) - * @display: (type GdkWaylandDisplay): a #GdkDisplay + * @display: (type GdkWaylandDisplay): a `GdkDisplay` * - * Returns the Wayland global singleton compositor of a #GdkDisplay. + * Returns the Wayland `wl_compositor` of a `GdkDisplay`. * - * Returns: (transfer none): a Wayland wl_compositor + * Returns: (transfer none): a Wayland `wl_compositor` */ struct wl_compositor * gdk_wayland_display_get_wl_compositor (GdkDisplay *display) @@ -2639,14 +2653,14 @@ gdk_wayland_display_get_output_scale (GdkWaylandDisplay *display_wayland, /** * gdk_wayland_display_query_registry: - * @display: (type GdkWaylandDisplay): a #GdkDisplay + * @display: (type GdkWaylandDisplay): a `GdkDisplay` * @global: global interface to query in the registry * * Returns %TRUE if the the interface was found in the display * `wl_registry.global` handler. * * Returns: %TRUE if the global is offered by the compositor - **/ + */ gboolean gdk_wayland_display_query_registry (GdkDisplay *display, const char *global) diff --git a/gdk/wayland/gdkglcontext-wayland.c b/gdk/wayland/gdkglcontext-wayland.c index a5939416f8..1667117e7f 100644 --- a/gdk/wayland/gdkglcontext-wayland.c +++ b/gdk/wayland/gdkglcontext-wayland.c @@ -35,6 +35,12 @@ #include "gdkintl.h" +/** + * GdkWaylandGLContext: + * + * The Wayland implementation of `GdkGLContext`. + */ + G_DEFINE_TYPE (GdkWaylandGLContext, gdk_wayland_gl_context, GDK_TYPE_GL_CONTEXT) static void gdk_wayland_gl_context_dispose (GObject *gobject); diff --git a/gdk/wayland/gdkmonitor-wayland.c b/gdk/wayland/gdkmonitor-wayland.c index e13a686055..165078df07 100644 --- a/gdk/wayland/gdkmonitor-wayland.c +++ b/gdk/wayland/gdkmonitor-wayland.c @@ -23,6 +23,16 @@ #include "gdkmonitor-wayland.h" +/** + * GdkWaylandMonitor: + * + * The Wayland implementation of `GdkMonitor`. + * + * Beyond the [class@Gdk.Monitor] API, the Wayland implementation + * offers access to the Wayland `wl_output` object with + * [method@GdkWayland.WaylandMonitor.get_wl_output]. + */ + G_DEFINE_TYPE (GdkWaylandMonitor, gdk_wayland_monitor, GDK_TYPE_MONITOR) static void @@ -50,11 +60,11 @@ gdk_wayland_monitor_class_init (GdkWaylandMonitorClass *class) /** * gdk_wayland_monitor_get_wl_output: (skip) - * @monitor: (type GdkWaylandMonitor): a #GdkMonitor + * @monitor: (type GdkWaylandMonitor): a `GdkMonitor` * - * Returns the Wayland wl_output of a #GdkMonitor. + * Returns the Wayland `wl_output` of a `GdkMonitor`. * - * Returns: (transfer none): a Wayland wl_output + * Returns: (transfer none): a Wayland `wl_output` */ struct wl_output * gdk_wayland_monitor_get_wl_output (GdkMonitor *monitor) diff --git a/gdk/wayland/gdksurface-wayland.c b/gdk/wayland/gdksurface-wayland.c index 06c5753757..c621a71344 100644 --- a/gdk/wayland/gdksurface-wayland.c +++ b/gdk/wayland/gdksurface-wayland.c @@ -43,6 +43,33 @@ #include #include +/** + * GdkWaylandSurface: + * + * The Wayland implementation of `GdkSurface`. + * + * Beyond the [class@Gdk.Surface] API, the Wayland implementation offers + * access to the Wayland `wl_surface` object with + * [method@GdkWayland.WaylandSurface.get_wl_surface]. + */ + +/** + * GdkWaylandToplevel: + * + * The Wayland implementation of `GdkToplevel`. + * + * Beyond the [interface@Gdk.Toplevel] API, the Wayland implementation + * has API to set up cross-process parent-child relationships between + * surfaces with [method@GdkWayland.WaylandToplevel.export_handle] and + * [method@GdkWayland.WaylandToplevel.set_transient_for_exported]. + */ + +/** + * GdkWaylandPopup: + * + * The Wayland implementation of `GdkPopup`. + */ + #define SURFACE_IS_TOPLEVEL(surface) TRUE #define MAX_WL_BUFFER_SIZE (4083) /* 4096 minus header, string argument length and NUL byte */ @@ -1865,10 +1892,10 @@ create_zxdg_toplevel_v6_resources (GdkSurface *surface) /** * gdk_wayland_toplevel_set_application_id: - * @toplevel: (type GdkWaylandToplevel): a #GdkToplevel + * @toplevel: (type GdkWaylandToplevel): a `GdkToplevel` * @application_id: the application id for the @toplevel * - * Sets the application id on a #GdkToplevel. + * Sets the application id on a `GdkToplevel`. */ void gdk_wayland_toplevel_set_application_id (GdkToplevel *toplevel, @@ -4225,11 +4252,11 @@ _gdk_wayland_surface_set_grab_seat (GdkSurface *surface, /** * gdk_wayland_surface_get_wl_surface: (skip) - * @surface: (type GdkWaylandSurface): a #GdkSurface + * @surface: (type GdkWaylandSurface): a `GdkSurface` * - * Returns the Wayland surface of a #GdkSurface. + * Returns the Wayland `wl_surface` of a `GdkSurface`. * - * Returns: (transfer none): a Wayland wl_surface + * Returns: (transfer none): a Wayland `wl_surface` */ struct wl_surface * gdk_wayland_surface_get_wl_surface (GdkSurface *surface) @@ -4416,14 +4443,17 @@ static const struct zxdg_exported_v1_listener xdg_exported_listener = { /** * GdkWaylandToplevelExported: - * @toplevel: (type GdkWaylandToplevel): the #GdkToplevel that is exported + * @toplevel: (type GdkWaylandToplevel): the `GdkToplevel` that is exported * @handle: the handle - * @user_data: user data that was passed to gdk_wayland_toplevel_export_handle() + * @user_data: user data that was passed to [method@GdkWayland.WaylandToplevel.export_handle] * * Callback that gets called when the handle for a surface has been - * obtained from the Wayland compositor. The @handle can be passed - * to other processes, for the purpose of marking surfaces as transient - * for out-of-process surfaces. + * obtained from the Wayland compositor. + * + * This callback is used in [method@GdkWayland.WaylandToplevel.export_handle]. + * + * The @handle can be passed to other processes, for the purpose of + * marking surfaces as transient for out-of-process surfaces. */ static gboolean @@ -4434,24 +4464,25 @@ gdk_wayland_surface_is_exported (GdkWaylandSurface *impl) /** * gdk_wayland_toplevel_export_handle: - * @toplevel: (type GdkWaylandToplevel): the #GdkToplevel to obtain a handle for + * @toplevel: (type GdkWaylandToplevel): the `GdkToplevel` to obtain a handle for * @callback: callback to call with the handle * @user_data: (closure): user data for @callback * @destroy_func: destroy notify for @user_data * * Asynchronously obtains a handle for a surface that can be passed - * to other processes. When the handle has been obtained, @callback - * will be called. + * to other processes. + * + * When the handle has been obtained, @callback will be called. * * It is an error to call this function on a surface that is already * exported. * - * When the handle is no longer needed, gdk_wayland_toplevel_unexport_handle() + * When the handle is no longer needed, [method@GdkWayland.WaylandToplevel.unexport_handle] * should be called to clean up resources. * * The main purpose for obtaining a handle is to mark a surface * from another surface as transient for this one, see - * gdk_wayland_toplevel_set_transient_for_exported(). + * [method@GdkWayland.WaylandToplevel.set_transient_for_exported]. * * Note that this API depends on an unstable Wayland protocol, * and thus may require changes in the future. @@ -4498,7 +4529,7 @@ gdk_wayland_toplevel_export_handle (GdkToplevel *toplevel, /** * gdk_wayland_toplevel_unexport_handle: - * @toplevel: (type GdkWaylandToplevel): the #GdkToplevel to unexport + * @toplevel: (type GdkWaylandToplevel): the `GdkToplevel` to unexport * * Destroys the handle that was obtained with * gdk_wayland_toplevel_export_handle(). @@ -4552,12 +4583,14 @@ static const struct zxdg_imported_v1_listener xdg_imported_listener = { /** * gdk_wayland_toplevel_set_transient_for_exported: - * @toplevel: (type GdkWaylandToplevel): the #GdkToplevel to make as transient + * @toplevel: (type GdkWaylandToplevel): the `GdkToplevel` to make as transient * @parent_handle_str: an exported handle for a surface * * Marks @toplevel as transient for the surface to which the given - * @parent_handle_str refers. Typically, the handle will originate - * from a gdk_wayland_toplevel_export_handle() call in another process. + * @parent_handle_str refers. + * + * Typically, the handle will originate from a + * [method@WaylandToplevel.export_handle] call in another process. * * Note that this API depends on an unstable Wayland protocol, * and thus may require changes in the future. -- 2.30.2